'\" te
.\" This manual page is derived from the DAT/uDAPL 1.2 specification.
.\" Portions Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DAT_IA_OPEN 3DAT "Jan 28, 2009"
.SH NAME
dat_ia_open \- open an Interface Adapter (IA)
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-ldat\fR [ \fIlibrary\fR\&.\|.\|. ]
#include <\fBdat/udat.h\fR>

DAT_RETURN
    dat_ia_open (
    IN const DAT_NAME_PTR       \fIia_name_ptr\fR,
    IN       DAT_COUNT          \fIasync_evd_min_qlen\fR,
    INOUT    DAT_EVD_HANDLE     *\fIasync_evd_handle\fR,
    OUT      DAT_IA_HANDLE      *\fIia_handle\fR
    )
.fi

.SH PARAMETERS
.sp
.ne 2
.na
\fB\fIia_name_ptr\fR\fR
.ad
.RS 22n
Symbolic name for the IA to be opened. The name should be defined by the
Provider registration.
.sp
If the name is prefixed by the string \fBRO_AWARE_\fR, then the prefix is
removed prior to being passed down and the existence of the prefix indicates
that the application has been coded to correctly deal with relaxed ordering
constraints. If the prefix is not present and the platform on which the
application is running is utilizing relaxed ordering, the open will fail with
\fBDAT_INVALID_PARAMETER\fR (with \fBDAT_SUBTYPE_STATUS\fR of
\fBDAT_INVALID_RO_COOKIE\fR). This setting also affects
\fBdat_lmr_create\fR(3DAT).
.RE

.sp
.ne 2
.na
\fB\fIasync_evd_min_qlen\fR\fR
.ad
.RS 22n
Minimum length of the Asynchronous Event Dispatcher queue.
.RE

.sp
.ne 2
.na
\fB\fIasync_evd_handle\fR\fR
.ad
.RS 22n
Pointer to a handle for an Event Dispatcher for asynchronous events generated
by the IA. This parameter can be \fBDAT_EVD_ASYNC_EXISTS\fR to indicate that
there is already EVD for asynchronous events for this Interface Adapter or
\fBDAT_HANDLE_NULL\fR for a Provider to generate EVD for it.
.RE

.sp
.ne 2
.na
\fB\fIia_handle\fR\fR
.ad
.RS 22n
Handle for an open instance of a DAT IA. This handle is used with other
functions to specify a particular instance of the IA.
.RE

.SH DESCRIPTION
.sp
.LP
The \fBdat_ia_open()\fR function opens an IA by creating an IA instance.
Multiple instances (opens) of an IA can exist.
.sp
.LP
The value of \fBDAT_HANDLE_NULL\fR for \fIasync_evd_handle\fR
(*\fIasync_evd_handle\fR == \fBDAT_HANDLE_NULL\fR) indicates that the default
Event Dispatcher is created with the requested \fIasync_evd_min_qlen\fR. The
\fIasync_evd_handle\fR returns the handle of the created Asynchronous Event
Dispatcher. The first Consumer that opens an IA must use \fBDAT_HANDLE_NULL\fR
because no EVD can yet exist for the requested \fIia_name_ptr\fR.
.sp
.LP
The Asynchronous Event Dispatcher (\fIasync_evd_handle\fR) is created with no
CNO (\fBDAT_HANDLE_NULL\fR). Consumers can change these values using
\fBdat_evd_modify_cno\fR(3DAT). The Consumer can modify parameters of the Event
Dispatcher using \fBdat_evd_resize\fR(3DAT) and \fBdat_evd_modify_cno()\fR.
.sp
.LP
The Provider is required to provide a queue size at least equal to
\fIasync_evd_min_qlen\fR, but is free to provide a larger queue size or
dynamically enlarge the queue when needed. The Consumer can determine the
actual queue size by querying the created Event Dispatcher instance.
.sp
.LP
If \fIasync_evd_handle\fR is not \fBDAT_HANDLE_NULL\fR, the Provider does not
create an Event Dispatcher for an asynchronous event and the Provider ignores
the \fIasync_evd_min_qlen\fR value. The \fIasync_evd_handle\fR value passed in
by the Consumer must be an asynchronous Event Dispatcher created for the same
Provider (\fIia_name_ptr\fR). The Provider does not have to check for the
validity of the Consumer passed in \fIasync_evd_handle\fR. It is the Consumer
responsibility to guarantee that \fIasync_evd_handle\fR is valid and for this
Provider. How the \fIasync_evd_handle\fR is passed between DAT Consumers is out
of scope of the DAT specification. If the Provider determines that the
Consumer-provided \fIasync_evd_handle\fR is invalid, the operation fails and
returns \fBDAT_INVALID_HANDLE\fR. The \fIasync_evd_handle\fR remains unchanged,
so the returned \fIasync_evd_handle\fR is the same the Consumer passed in. All
asynchronous notifications for the open instance of the IA are directed by the
Provider to the Consumer passed in Asynchronous Event Dispatcher specified by
\fIasync_evd_handle\fR.
.sp
.LP
Consumer can specify the value of \fBDAT_EVD_ASYNC_EXISTS\fR to indicate that
there exists an event dispatcher somewhere else on the host, in user or kernel
space, for asynchronous event notifications. It is up to the Consumer to ensure
that this event dispatcher is unique and unambiguous. A special handle may be
returned for the Asynchronous Event Dispatcher for this scenario,
\fBDAT_EVD_OUT_OF_SCOPE\fR, to indicate that there is a default Event
Dispatcher assigned for this Interface Adapter, but that it is not in a scope
where this Consumer may directly invoke it.
.sp
.LP
The Asynchronous Event Dispatcher is an Object of both the Provider and IA.
Each Asynchronous Event Dispatcher bound to an IA instance is notified of all
asynchronous events, such that binding multiple Asynchronous Event Dispatchers
degrades performance by duplicating asynchronous event notifications for all
Asynchronous Event Dispatchers. Also, transport and memory resources can be
consumed per Event Dispatcher bound to an IA
.sp
.LP
As with all Event Dispatchers, the Consumer is responsible for synchronizing
access to the event queue.
.sp
.LP
Valid IA names are obtained from \fBdat_registry_list_providers\fR(3DAT).
.SH RETURN VALUES
.sp
.ne 2
.na
\fB\fBDAT_SUCCESS\fR\fR
.ad
.RS 30n
The operation was successful.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INSUFFICIENT_RESOURCES\fR\fR
.ad
.RS 30n
The operation failed due to resource limitations.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_PARAMETER\fR\fR
.ad
.RS 30n
Invalid parameter.
.RE

.sp
.ne 2
.na
\fB\fBDAT_PROVIDER_NOT_FOUND\fR\fR
.ad
.RS 30n
The specified provider was not registered in the registry.
.RE

.sp
.ne 2
.na
\fB\fBDAT_INVALID_HANDLE\fR\fR
.ad
.RS 30n
Invalid DAT handle; async_evd_handle is invalid.
.RE

.SH USAGE
.sp
.LP
The \fBdat_ia_open()\fR function is the root method for the Provider, and,
thus, all Objects. It is the root handle through which the Consumer obtains all
other DAT handles. When the Consumer closes its handle, all its DAT Objects are
released.
.sp
.LP
The \fBdat_ia_open()\fR function is the workhorse method that provides an IA
instance. It can also initialize the Provider library or do any other
registry-specific functions.
.sp
.LP
The \fBdat_ia_open()\fR function creates a unique handle for the IA to the
Consumer. All further DAT Objects created for this Consumer reference this
handle as their owner.
.sp
.LP
The \fBdat_ia_open()\fR function can use a reference count for the Provider
Library to ensure that the Provider Library cannot be removed when it is in use
by a DAT Consumer.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Safe
_
Standard	uDAPL, 1.1, 1.2 (except \fBRO_AWARE_\fR)
.TE

.SH SEE ALSO
.sp
.LP
.BR dat_evd_modify_cno (3DAT),
.BR dat_evd_resize (3DAT),
.BR dat_ia_close (3DAT),
.BR dat_registry_list_providers (3DAT),
.BR libdat (3LIB),
.BR attributes (7)
